---
title: Render Plugin
description: Provides the essential <RenderLayer /> component for visually rendering PDF pages.
searchable: true
---

# Render Plugin

The Render Plugin is the visual heart of the PDF viewer. It's responsible for taking the PDF data from the core engine and "painting" it onto the screen for the user to see. Its primary feature is the fundamental `<RenderLayer />` component.

## Installation

The plugin is available as a separate NPM package and is essential for any visual viewer.

```sh npm2yarn
npm install @embedpdf/plugin-render
````

## Registration

Import `RenderPluginPackage` and add it to the `plugins` array. This plugin has no configuration options.

```tsx {4, 13}
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/react'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),

  // Register the render plugin
  createPluginRegistration(RenderPluginPackage),
]
```

## Usage

The plugin can be used in two ways: the simple `<RenderLayer />` component for displaying pages within the viewer, and the `useRenderCapability` hook for more advanced, on-demand rendering tasks.

### Primary Usage: The `<RenderLayer />` Component

This is the most common and straightforward way to render a PDF page. You should place the `<RenderLayer />` component inside the `renderPage` prop of your `<Scroller />`. It will automatically render the correct page at the correct size and resolution as the user scrolls.

```tsx {5}
<Scroller
  renderPage={({ width, height, pageIndex, scale }) => (
    <div style={{ width, height, position: 'relative' }}>
      {/* The RenderLayer is responsible for drawing the page */}
      <RenderLayer pageIndex={pageIndex} scale={scale} />
    </div>
  )}
/>
```

### Advanced Usage: On-Demand Rendering

For custom features that require rendering a page outside the main viewer—such as exporting a page as a high-resolution image—you can use the `useRenderCapability` hook. This gives you direct access to the plugin's rendering functions.

```tsx {2, 5, 10}
import { useState } from 'react';
import { useRenderCapability } from '@embedpdf/plugin-render/react';

const ExportButton = () => {
  const { provides: render } = useRenderCapability();
  const [isExporting, setIsExporting] = useState(false);

  const exportPage = () => {
    setIsExporting(true);
    const task = render.renderPage({ pageIndex: 0, options: { scaleFactor: 3.0 } });
    task.wait(blob => {
      // ... trigger download from the blob ...
      setIsExporting(false);
    });
  };

  return <button onClick={exportPage}>{isExporting ? '...' : 'Export Page'}</button>
}
```

## Live Example

This example shows a standard PDF viewer, but with a toolbar button that uses the `useRenderCapability` hook to export the first page as a high-resolution PNG file.

import { PDFViewer } from '../code-examples/render-example';

<PDFViewer />

## API Reference

### Component: `<RenderLayer />`

The component that renders a single PDF page as an image.

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | (Required) The index of the page to render. |
| **`scale`** | `number` | The scale factor for rendering the page. A higher number results in a higher resolution image. |
| **`dpr`** | `number` | The device pixel ratio to use for rendering, for crisp text on high-DPI screens. <br/>**Default**: `window.devicePixelRatio` |

### Hook: `useRenderCapability()`

Connects your component to the render plugin's low-level functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`** | `RenderCapability \| null` | An object with methods to render pages, or `null` if the plugin is not ready. |

#### `RenderCapability` Methods

| Method | Description |
| :--- | :--- |
| **`renderPage(options)`** | Renders a full page. The `options` object takes a `pageIndex` and a `PdfRenderPageOptions` object. Returns a `Task<Blob>`. |
| **`renderPageRect(options)`** | Renders a specific rectangular portion of a page. Useful for creating snapshots. Returns a `Task<Blob>`. |

#### `PdfRenderPageOptions`

| Option | Type | Description |
| :--- | :--- | :--- |
| **`scaleFactor`**| `number`| The scale to render at. **Default**: `1.0`. |
| **`rotation`** | `Rotation` | Applies a rotation to the rendered output. **Default**: `Rotation.Degree0`. |
| **`dpr`**| `number` | The device pixel ratio. **Default**: `window.devicePixelRatio`. |
| **`withAnnotations`** | `boolean` | Whether to include annotations in the render. **Default**: `true`. |
| **`imageType`** | `string` | The image format for the output, e.g., `'image/webp'`, `'image/jpeg'`, or `'image/png'`. **Default**: `'image/webp'`. |
| **`imageQuality`** | `number` | A value between 0 and 1 indicating the quality for lossy formats like `'image/jpeg'` and `'image/webp'`. |